home *** CD-ROM | disk | FTP | other *** search
/ Power Programmierung 2 / Power-Programmierung CD 2 (Tewi)(1994).iso / c / library / dos / tvision / tfield / tdate.doc < prev    next >
Encoding:
Text File  |  1991-08-05  |  8.1 KB  |  185 lines
  1. Documentation for Version 3.00
  2. ==============================
  3.  
  4. In the beginning Steve Marcus (CIS 72007,1233) posted a basic date
  5. manipulation/arithmetic class produced with Borland C++ 2.0 in the 
  6. BPROGB forum, with a request for suggestions and enhancements. This was
  7. on 6/19/91.
  8.  
  9. A rather enterprising gentleman by the name of Eric Simon (CIS 70540,1522)
  10. accepted the challenge, and produced a new and improved version in the 
  11. course of a project he was developing at work. He contributed the results
  12. to the forum on 6/29/91, also inviting enhancements and comments.
  13.  
  14. Coincidentally, I developed a need for a universal date conversion routine
  15. about the same time for use in a business project I was developing as well.
  16. Browsing the same forum, I encountered Eric's class, which provided much of
  17. the functionality I needed  - the basic julian-gregorian and day of week
  18. conversion algorithms - relieving me of the task of researching or re-
  19. inventing them. He had also added overloaded + and - operators for
  20. incrementing date objects by integer days, as well as several print functions.
  21.  
  22. I needed additional features for my implementations, so I set about adding
  23. to the class. As is my habit, I got carried away. 
  24.  
  25. The class now has:
  26.  
  27.     1. A full set of constructors, allowing    construction and re-setting
  28.     of any date object from a julian date (the universal kind, relative
  29.     to 1/1/4713 B.C.E., not the YYDDD kind); from a date string (i.e. 
  30.     11/15/1991);from another date object (copy constructor); or from a
  31.     "date" struct as defined in dos.h and returned by getdate(). A date
  32.     object may also be set to the current system date by assigning it to 
  33.     the string "today" (case-insensitive).
  34.  
  35.     2. A full set of comparison operators ( <, <=, >, >=, ==, !=), 
  36.     defined as friend functions so that date objects may be freely
  37.     compared to other date objects, to julian dates, or to strings.
  38.  
  39.     3. A full set of arithmetic operators ( +, -, ++, --, += and -=).
  40.     Additionally, two date objects may now be subtracted to find the
  41.     number of days between them.
  42.  
  43.     4. I have consolidated the print functions into one function,
  44.     formatDate, which accepts an enum value as its format type.
  45.  
  46.     MDY  - returns a buffer with the date formatted as MM/DD/YYYY
  47.     DAY  - returns a buffer with the day of the week name only
  48.     MONTH- returns a buffer with the month name only
  49.     FULL - returns a buffer with the date formatted as DAY MMMMM DD, YYYY
  50.     EUROPEAN- returns a buffer with the date formatted as DD MMMMMM, YYYY
  51.  
  52.     5. The ostream << operator has been overloaded as a friend function
  53.     to handle Date objects. In this implementation the format returned
  54.     is fixed at MM/DD/YYYY, however an equivalent to the ios::setf
  55.     function could be added to maintain a static member in the Date
  56.     class to handle multiple formatting options. A companion << operator
  57.     has been included to handle dos.h date structs, which are returned
  58.     by the getDate() function.
  59.  
  60.     6. Several utility functions have been provided:
  61.  
  62.         isLeapYear - returns 1 if a leap year, 0 if not
  63.         dayOfYear  - returns the day relative to Jan. 1
  64.         eom        - returns a dos.h "date" struct (format YYYYDDMM)
  65.                  with the last day of the month of the date object
  66.         getDate    - returns a dos.h "date" struct (format YYYYDDMM)
  67.                  equivalent to the date object
  68.  
  69.  
  70. IMPLEMENTATION NOTES.
  71.  
  72.     I have attempted to optimize the code for the Borland C++ compiler,
  73.     including the specification of const where applicable, the passing
  74.     of references where advisable, and the use of constructor initializers
  75.     where needed. However I have not made an exhaustive analysis of this
  76.     subject.
  77.  
  78.     Those of you who are using Eric's version will note that I have 
  79.     capatilized the class name to Date, to avoid conflict with Borland's
  80.     "date" struct defined in DOS.H, which is also used by two functions.
  81.     Please be wary of the potential for capitalization errors here.
  82.     Also, I have altered the capitalization    of several function names
  83.     to conform with Borland's suggested convention.
  84.  
  85.     Also, I reorganized the source according to common distribution
  86.     formats.
  87.  
  88.     Thus, this ZIP file contains:
  89.  
  90.         DATECLS3.HPP    -     the header file
  91.         DATECLS3.CPP    -    the member functions
  92.         DATEDEMO.CPP    -    a test program (and a messy one at that)
  93.         DATECLS3.DOC    -    the file you're reading
  94.  
  95.     
  96. Future possibilities for enhancement include:
  97.     
  98.     1. Maintenance of a static variable to handle global date format
  99.        preferences (MDY, FULL, etc.) which would be used to control
  100.        the overloaded << operator (now fixed at the MDY format). This
  101.        would be more convenient than using the formatDate routine.
  102.  
  103.     2. Maintenance of a static variable to handle other print format
  104.        preferences. (Ideas would be to strip the century from the
  105.        MDY format (i.e 10/15/91 instead of 10/15/1991), print 
  106.        abbreviated day or month names (i.e. MON, TUE, JAN, FEB), and
  107.        the like). This would probably be a set of bit flags which would
  108.        work (and be set) like the ios::setf options.
  109.  
  110.     3. Adding a derived Time class, for those applications which require
  111.        the ability to track more than just dates. This would allow the
  112.        manipulation of times for all dates (not just since 1980), and
  113.        arithmetic calculations as well.
  114.  
  115. This is a truly pleasing example of co-operation among professionals, and 
  116. an "object" study in the code reusability of OOP, resulting in three releases
  117. of one class within a single month by three different analysts who have never
  118. met. I thank Steve and Eric for their inspiration and generousity, and hereby
  119. contribute my additions to the public domain.
  120.  
  121. I would welcome further comments, suggestions and enhancements as well.
  122. Good luck!
  123.  
  124.                     Christopher Hill
  125.                     72030,2606
  126.  
  127.  
  128. Documentation notes for Version 3.1
  129. ===================================
  130.  
  131. Subsequent to release 3.00, we (Hill & Simon) decided to collaborate on
  132. several further releases of this date class. This, the first, contains two
  133. new features, as well as a few minor bug fixes.
  134.  
  135. 1. There was a minor bug in the original Computer Language julian/gregorian
  136.    date conversion routines having to do with negative years.
  137.  
  138. 2. The isLeapYear function did not take into account that, prior to 1582,
  139.    years ending in 00 were also leap years.
  140.  
  141. 3. The two-dimensional array of the number of days in each month has been
  142.    eliminated in favor of a computational approach.
  143.  
  144. 4. We have implemented suggestions 1 & 2 from the wish list above. The
  145.    function Date::setFormat(XXXX) maintains a static variable (one occurance
  146.    for all Date objects, which controls the format which the << operator
  147.    uses to print objects. "XXXX" can be MONTH, MDY, DAY, FULL, or EUROPEAN.
  148.    The setting defaults to MDY, but once altered, remains altered until reset
  149.    by another call to setFormat.
  150.  
  151.    The function Date::setOption(Option, Action) maintains a similar static
  152.    variable which enables certain print formatting options. Available options
  153.    at this point are:
  154.  
  155.             NO_CENTURY    --    Suppress the printing of the century when
  156.                                 in the MDY format (ex: 01/01/91 instead of
  157.                                 01/01/1991).
  158.  
  159.             DATE_ABBR     --    Abbreviate month and day names when printing
  160.                                 in the MONTH, DAY, FULL or EUROPEAN formats.
  161.                                 (ex. MON, TUE, JAN, FEB, etc.) The length
  162.                                 or the abbreviation is controlled by a
  163.                                 DEFINED constant in DATECL31.HPP named
  164.                                 ABBR_LENGTH, preset to 3.
  165.  
  166.    "Action" is either ON or OFF, and defaults to ON. (Example, the call
  167.    Date::setOption(NO_CENTURY) turns on the century suppression option, and
  168.    it remains set until the call Date::setOption(NO_CENTURY, OFF) is made.
  169.  
  170.  
  171.    More features, including further expanded print formatting features,
  172.    the derived Time class mentioned above, conversion into various calendar
  173.    formats (Jewish, Chinese, Arabic, etc.), ability to increment Date objects
  174.    by years and months instead of merely days, holiday computations, and more
  175.    are planned. Stay tuned.
  176.  
  177.     Any questions, comments, or suggestions are welcomed. Please contact
  178.     either of us.
  179.  
  180.  
  181.                 Christopher Hill                Eric Simon
  182.                 72030,2606                        70540,1522
  183.  
  184.  
  185.